--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Node / ReticulumProjects / MeshChatX.git / files / meshchatx / src / frontend / public / meshchatx-docs / en / getting-started.md
meshchatx/src/frontend/public/meshchatx-docs/en/getting-started.md dff83e198e78b84ec225e53ce3ab119f598b0a01 (dff83e19) Text, 6.83 KB
Getting started with MeshChatX
MeshChatX is a local-first mesh communications client built on the Reticulum Network Stack. It combines direct messaging over LXMF, voice calls over LXST, NomadNet page browsing, relay chat, maps, and a large set of Reticulum utilities in one application you can run on a desktop, a headless server, or a mobile device.
MeshChatX is an independent fork of Reticulum MeshChat. It is not affiliated with the upstream project. The website is meshchatx.com. Source and releases live on GitHub.
What you need to know first
Reticulum is the mesh networking layer. It handles identities, paths, interfaces, and encrypted transport between nodes. LXMF is the messaging protocol MeshChatX uses for conversations, attachments, and propagation. LXST is the telephony layer used for audio calls.
MeshChatX does not replace Reticulum. It runs Reticulum inside a Python process, exposes a web UI, and stores your per-identity data locally in SQLite.
How the application is laid out
When you open MeshChatX you work inside a single-page web interface. The sidebar lists the main areas of the app. The Tools page groups diagnostics and utilities. Settings holds per-identity configuration. Identities lets you create or switch between separate cryptographic identities.
Typical first-day workflow:
1. Install MeshChatX using a method that fits your device. See Installation and setup.
2. Open the web UI. The default address is T383838https://127.0.0.1:8000 when HTTPS is enabled.
3. Go to Interfaces and add a way to reach the mesh. A TCP client, community interface suggestion, or LoRa RNode are common starting points.
4. Wait for paths and announces to populate. Peers appear in the announces list and in feature-specific views.
5. Open Messages to start an LXMF conversation, or Nomad Network to browse a page node.
Runtime shape
MeshChatX ships as one Python service that serves both the API and the built frontend assets.
T282828
Browser or Electron window
|
v
Vue 3 frontend (hash routes such as #/messages)
|
| REST under /api/v1/* and WebSocket at /ws
v
meshchatx/meshchat.py (aiohttp server)
|
+--> SQLite database (per identity)
+--> LXMF router and message store
+--> LXST telephone (when enabled)
+--> Reticulum stack (interfaces, paths, announces)
The same backend code powers Docker images, Python wheels, Linux packages, Electron desktop builds, and the Android APK. Packaging differs. Behaviour is intended to stay consistent.
In a regular browser (including headless or LAN installs), MeshChatX may register a service worker that caches hashed UI assets and the app shell so repeat loads are faster and a hard refresh can still show the boot splash while the local backend restarts. Mesh messaging, identity, and API data still require the Python backend. Electron does not use this service worker path.
Main areas of the UI
┌────────────────────┬─────────────────────┬───────────────────────────────────────────────────────┐
│ Area │ Route │ Purpose │
├────────────────────┼─────────────────────┼───────────────────────────────────────────────────────┤
│ Messages │ T383838/messages │ LXMF direct messaging, folders, attachments │
│ Audio calls │ T383838/call │ LXST voice calls and voicemail │
│ Contacts │ T383838/contacts │ Telephone contacts and call-related entries │
│ Relay chat │ T383838/relay-chat │ RRC hubs and rooms (when enabled in settings) │
│ Nomad Network │ T383838/nomadnetwork │ Browse remote NomadNet pages and files │
│ Map │ T383838/map │ OpenLayers map, offline tiles, telemetry │
│ Archives │ T383838/archives │ Versioned snapshots of Nomad pages │
│ Tools │ T383838/tools │ Ping, path tools, RNCP, bots, documentation, and more │
│ Interfaces │ T383838/interfaces │ Add and manage Reticulum interfaces │
│ Network visualiser │ T383838/network-visualiser │ Graph view of mesh topology │
│ Blocked │ T383838/blocked │ Blocked destinations │
│ Settings │ T383838/settings │ Theme, language, LXMF, telephone, security │
│ Identities │ T383838/identities │ Create, import, or switch identities │
│ Documentation │ T383838/documentation │ MeshChatX guides and the Reticulum manual │
└────────────────────┴─────────────────────┴───────────────────────────────────────────────────────┘
Relay chat appears only when T383838rrc_enabled is turned on in settings. When enabled, the Relay chat icon can show a red mention count. Messages shows unread conversation count. Calls shows unread missed-call count.
Documentation in the app
The Documentation page has two tabs.
MeshChatX shows the guides in this bundle. They are markdown files synced from the T383838docs/ directory in the repository and rendered offline inside the app.
Reticulum shows the upstream Reticulum manual as pre-built HTML. It is bundled at build time. You can upload a newer manual ZIP if you need a different version.
Use the search bar to query both sets at once. MeshChatX guide text is currently available in English. The Reticulum manual body is English. Localized landing pages exist for several languages on the Reticulum tab.
Storage locations
┌───────────────────────┬──────────────────────────────────────────────────┐
│ Data │ Typical path │
├───────────────────────┼──────────────────────────────────────────────────┤
│ MeshChatX app data │ T383838~/.reticulum-meshchatx/ on Linux and macOS │
│ Reticulum config │ T383838~/.reticulum/ │
│ Per-identity database │ T383838<storage>/identities/<identity_hash>/database.db │
│ Docker volume │ T383838meshchatx-config mounted at T383838/config │
└───────────────────────┴──────────────────────────────────────────────────┘
Legacy upstream data may still exist under T383838~/.reticulum-meshchat/. Migration tooling can move you to the MeshChatX layout.
Where to go next
• Installation and setup covers Docker, wheels, desktop packages, and development builds.
• Architecture and design explains backend managers, identity scoping, and the API model.
• LXMF messaging and Audio calls describe day-to-day communication features.
• Reticulum interfaces explains how your node joins the mesh.
• Platform guides under Platform guides cover Raspberry Pi, Android Termux, Meta Quest, Linux sandboxing, and Windows AppContainer sandboxing.
For protocol-level detail, open the Reticulum tab in Documentation or visit the Reticulum manual online.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────